Skip to content

docs(ams): port docs/env-reference.md to a generated website docs page (docs.ams-env-reference.tsx) - #6376

Closed
oktofeesh1 wants to merge 3 commits into
JSONbored:mainfrom
oktofeesh1:docs/ams-env-reference-6028
Closed

docs(ams): port docs/env-reference.md to a generated website docs page (docs.ams-env-reference.tsx)#6376
oktofeesh1 wants to merge 3 commits into
JSONbored:mainfrom
oktofeesh1:docs/ams-env-reference-6028

Conversation

@oktofeesh1

Copy link
Copy Markdown
Contributor

Summary

  • Extends packages/loopover-miner/scripts/generate-env-reference.mjs to also emit apps/loopover-ui/src/lib/ams-env-reference.ts (AMS_ENV_REFERENCE_ROWS + AMS_ENV_REFERENCE_MARKDOWN), mirroring scripts/gen-selfhost-env-reference.mjs's renderSelfHostEnvReferenceModule exactly. npm run miner:env-reference(:check) now writes/verifies both the existing markdown doc and the new TS module, so a new LOOPOVER_MINER_*/MINER_* read still fails CI drift-check until both are regenerated.
  • packages/loopover-miner/docs/env-reference.md is untouched in content (still generator-owned, "do not edit manually") and stays the canonical source shipped in the npm package — no hand-written pointer note added to it, since the generator would just flag it as stale.
  • Adds content/docs/ams-env-reference.mdx, which imports AMS_ENV_REFERENCE_MARKDOWN and renders it via <CodeBlock> — the same pattern docs.self-hosting-configuration.tsx already uses for SELFHOST_ENV_REFERENCE_MARKDOWN — not a hand-copied table, per the issue's explicit requirement.
  • Adds apps/loopover-ui/src/routes/docs.ams-env-reference.tsx, a thin loader + docsClientLoader route matching every other migrated docs page.
  • Adds the page to docs-nav.tsx's "AMS: deployment" subgroup and to docs.index.tsx's Maintainers audience card, and repoints ams-operations-runbook.mdx's and ams-config-precedence.mdx's GitHub-blob env-reference.md cross-references to the new in-app route.
  • Extends test/unit/miner-env-reference-script.test.ts with module-generation and drift-detection tests mirroring test/unit/selfhost-env-reference-script.test.ts.

Two follow-on fixes landed in separate commits after the initial gate run surfaced them:

  • packages/loopover-miner/scripts/generate-env-reference.d.mts (a hand-maintained sidecar declaration file) needed the new exports added — root tsc --noEmit resolves types for .mjs files from their .d.mts sidecar, not the implementation, so it failed with "has no exported member" until the sidecar was updated.
  • The generated module's markdown lines that embed a quoted-string default value (rendered as `""` / `"production"` in the table) contain literal double quotes; JSON.stringify-ing those lines always double-quotes the JS string literal, which ui:lint's prettier/prettier rule then flags for reformatting to single quotes (fewer escapes) despite the project's singleQuote: false default. Since this is a generated file, a one-off --fix would be undone by the next npm run miner:env-reference — fixed by replicating Prettier's fewer-escapes quote choice directly in the generator (quoteJsStringLiteral).

Scope

Validation

  • git diff --check
  • npm run actionlint
  • npm run typecheck
  • npm run test:coverage locally — packages/loopover-miner/scripts/** is outside vitest's coverage-collection scope (only src/**, packages/loopover-engine/src/**, and packages/loopover-miner/lib/** are instrumented per codecov.yml's own comment), and the .tsx/.mdx page is outside coverage.include; codecov/patch does not apply. New generator behavior is still covered by real unit tests regardless.
  • npm run test:workers
  • npm run build:mcp
  • npm run test:mcp-pack
  • npm run ui:openapi:check
  • npm run ui:lint
  • npm run ui:typecheck
  • npm run ui:build
  • npm audit --audit-level=moderate
  • npm run miner:env-reference:check passes for both generated outputs
  • Full npm run test:ci run locally from a clean npm ci install, green: 905 test files / 17,282 tests passed (three full runs total — the first two caught the .d.mts and Prettier-quoting issues above, both fixed and re-verified)
  • npx eslint apps/loopover-ui/src/lib/ams-env-reference.ts run directly against the generated output to confirm it's lint-clean

Safety

  • No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
  • Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
  • Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests. — N/A, no such changes in this PR
  • API/OpenAPI/MCP behavior is updated and tested where needed. — the generator's new module-emitting behavior is covered by new unit tests
  • UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. — N/A, static generated reference content only
  • Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

Notes

…e (docs.ams-env-reference.tsx)

Extend packages/loopover-miner/scripts/generate-env-reference.mjs to also
emit apps/loopover-ui/src/lib/ams-env-reference.ts (AMS_ENV_REFERENCE_ROWS +
AMS_ENV_REFERENCE_MARKDOWN), mirroring scripts/gen-selfhost-env-reference.mjs's
renderSelfHostEnvReferenceModule exactly. npm run miner:env-reference(:check)
now writes/verifies both the existing markdown doc and the new TS module, so
a new LOOPOVER_MINER_*/MINER_* read still fails CI drift-check until both are
regenerated. packages/loopover-miner/docs/env-reference.md is untouched in
content (still generator-owned, "do not edit manually") and stays the
canonical source shipped in the npm package.

Add content/docs/ams-env-reference.mdx, which imports AMS_ENV_REFERENCE_MARKDOWN
and renders it via <CodeBlock>, the same pattern
docs.self-hosting-configuration.tsx already uses for
SELFHOST_ENV_REFERENCE_MARKDOWN -- not a hand-copied table. Add the page to
docs-nav.tsx's "AMS: deployment" subgroup and to docs.index.tsx's Maintainers
audience card, and repoint ams-operations-runbook.mdx's and
ams-config-precedence.mdx's GitHub-blob env-reference.md cross-references to
the new in-app route.

Extend test/unit/miner-env-reference-script.test.ts with module-generation
and drift-detection tests mirroring test/unit/selfhost-env-reference-script.test.ts.
… module-generation exports

Root tsc --noEmit resolves types for generate-env-reference.mjs from its
hand-maintained .d.mts sidecar, not from the .mjs source -- the sidecar was
missed when renderMinerEnvReferenceModule/writeMinerEnvReferenceModule/
DEFAULT_MODULE_OUTPUT_PATH were added, so root typecheck failed with
"has no exported member" even though the .mjs implementation was correct.
…eration time

The project's Prettier config prefers double quotes (singleQuote: false) but
still switches a given string to single quotes when that needs fewer
escapes. Every markdown line whose row has a quoted-string defaultValue
(rendered as `""` / `"production"` in the table) embeds literal double
quotes, so JSON.stringify-ing that line (always double-quoted) produced
output ui:lint's prettier/prettier rule immediately flagged as needing
single-quote reformatting -- and since this file is generated, a one-off
--fix would just be undone by the next `npm run miner:env-reference`.

Replicate Prettier's fewer-escapes quote choice in the generator itself
(quoteJsStringLiteral), so a fresh run's output is already lint-clean.
@oktofeesh1
oktofeesh1 requested a review from JSONbored as a code owner July 16, 2026 05:04
@superagent-security

Copy link
Copy Markdown
Contributor

Superagent didn't find any vulnerabilities or security issues in this PR.

@codecov

codecov Bot commented Jul 16, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.60%. Comparing base (b7e1bec) to head (2a1950a).
⚠️ Report is 15 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #6376   +/-   ##
=======================================
  Coverage   95.60%   95.60%           
=======================================
  Files         599      599           
  Lines       47221    47221           
  Branches    15024    15024           
=======================================
  Hits        45147    45147           
  Misses       1290     1290           
  Partials      784      784           
Flag Coverage Δ
shard-1 44.00% <ø> (-0.18%) ⬇️
shard-2 36.79% <ø> (+0.39%) ⬆️
shard-3 32.29% <ø> (-0.23%) ⬇️
shard-4 34.69% <ø> (+0.07%) ⬆️
shard-5 31.45% <ø> (-0.15%) ⬇️
shard-6 45.32% <ø> (+0.44%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

@loopover-orb loopover-orb Bot added the gittensor:feature Gittensor-scored feature linked to a feature issue — scores a 0.25x multiplier. label Jul 16, 2026
@loopover-orb

loopover-orb Bot commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

Caution

🛑 LoopOver review result - fixes required

Review updated: 2026-07-16 05:23:55 UTC

11 files · no blockers · CI failing · blocked

🛑 Suggested Action - Fix Blockers

  • AI review already in progress for this PR head: Another LoopOver pass is already running the AI review for this exact PR head. This pass is skipping to avoid a duplicate LLM call.

Review summary
AI review is already running for this PR head in another LoopOver pass. LoopOver is holding this PR for manual review until that pass completes.

Nits — 1 non-blocking
  • AI review already in progress for this PR head — The gate is held for a human reviewer rather than passed automatically; it re-evaluates once the in-flight review completes or on the next update.

CI checks failing

  • validate
  • validate-code

Decision drivers

  • ✅ Code review — No blockers (No AI review summary)
  • ⚠️ Gate result — Not blocking (Advisory; not blocking this PR.)
Context & advisory signals — never blocks the verdict
Signal Result Evidence
Linked issue ✅ Linked #6028
Related work ⚠️ 3 scoped overlaps Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope ❌ 8/20 High review scope from cached public metadata (1 linked issue).
Validation posture ✅ 25/25 PR body includes validation/test evidence.
Contributor workload ✅ 10/10 Author activity: 63 registered-repo PR(s), 51 merged, 0 issue(s).
Contributor context ✅ Confirmed Gittensor contributor oktofeesh1; Gittensor profile; 63 PR(s), 0 issue(s).
Improvement ✅ Minor risk: clean · value: minor
Review context
  • Author: oktofeesh1
  • Role context: outside_contributor
  • Public audience mode: oss maintainer
  • Lane context: Repository is configured for direct PR review.
  • Public profile languages: not available
  • Official Gittensor activity: 63 PR(s), 0 issue(s).
  • Related work: Titles/paths share 6 meaningful terms. (issue #6031)
  • Related work: Titles/paths share 6 meaningful terms. (issue #6030)
  • Related work: Titles/paths share 6 meaningful terms. (issue #6029)
  • Additional title-only matches omitted; title-only overlap does not block.
Contributor next steps
  • Start here: Review top overlaps.
  • Then work through the remaining 3 steps in the Signals table above.
Signal definitions
  • Related work = same linked issue, overlapping active PRs, or title/path similarity.
  • Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
  • Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
  • Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
  • Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.
🧪 Chat with LoopOver

Ask LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

  • @loopover ask &lt;question&gt; answers contribution-quality Q&A with source citations and freshness.
  • @loopover chat &lt;question&gt; answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
  • A plain-language @loopover mention with a real question is routed to the closest matching read-only command automatically — no exact syntax required.

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

Visual preview
Route Viewport Before (production) After (this PR's preview) Diff
/docs/ams-env-reference desktop before /docs/ams-env-reference
before /docs/ams-env-reference
after /docs/ams-env-reference
after /docs/ams-env-reference
/docs/ams-env-reference mobile before /docs/ams-env-reference (mobile)
before /docs/ams-env-reference (mobile)
after /docs/ams-env-reference (mobile)
after /docs/ams-env-reference (mobile)
/docs desktop before /docs
before /docs
after /docs
after /docs
/docs mobile before /docs (mobile)
before /docs (mobile)
after /docs (mobile)
after /docs (mobile)

Click any thumbnail to open the full-size screenshot. Before = production · After = this PR's preview deploy.

🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed


💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by LoopOver, a quiet PR intelligence layer for OSS maintainers.

  • Re-run LoopOver review

@loopover-orb

loopover-orb Bot commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

LoopOver is closing this pull request on the maintainer's behalf (CI is failing (validate, validate-code)). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs may be analyzed later to improve review accuracy, but they are not automatically reopened or re-reviewed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

gittensor:feature Gittensor-scored feature linked to a feature issue — scores a 0.25x multiplier.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(ams): port docs/env-reference.md to a generated website docs page (docs.ams-env-reference.tsx)

1 participant